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A Mechanism for Converting Between 
Java Classes and XML 

Overview 

Java and XML (extensible Markup Language) technologies provide developers with the tools to 
write portable code and operate on portable data. Support for XML in the Java platform is 
increasing with the availability of standard APIs and parsers such as SAX and DOM (Document 
Object Modd). While these APIs provide standard mechanisms for reading XML documents, they 
work at a relatively low level. Using DOM for example, developers must have a detailed 
understanding of how to use the API to navigate nodes, elements and attributes to extract textual 
content, and then convert the text to useful program data types. This may be tedious, error prone, 
and requires the developer to work with classes outside the application domain. 

This paper describes a mechanism that allows developers to convert easily between Java and XML 
representations of data while working exclusively with classes from the application domain. With 
very little work, developers can add XML support for complex hierarchies of any user defined class, 
Java primitives and wrapper classes (Integer, Boolean, Float, etc.) as well as collections of such 
objects. 

A proposal by Sun Miaosystems has been drafted that deals with this topic using a different 
approach (An XML Data-Binding Facility for the Java Platform, hdarkReinhold, Core Java 
Platform Group, 30 July J 999 - see wwwJayasoft.com/xml). They propose a schema compiler that 
generates Java classes from an XML schema. The API proposed in this paper has the following 
advantages: 

• No schema compiler is required to generate new Java classes, 

t > New or existing classes can be easily annotated to work with the API. 

• The developer has full control and flexibility over how the classes get mapped to XML. Tv/o 
totally different dass implementations can work with the same XML representation in different 
ways. 

The following sections discuss how the API is used including the API class descriptions. 

An Example 

Data is described in XML in a hierarchical way by tagging elements. An XML document contains 
one single element (the document element) which may contain any number of other elements. For 
example, a XML representation of a book store may be: 

<bookStore> 

<naxQB>Th6 Frograimncr' s Book 3tore</name> 

<3treet>l Industrial Way</street> 
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<cit y2>Middle tovm< / ci t y > 
<state>iIJ</state> 
<2ip>0770K/2ip> 
</«cldrefl3> 

<hQ0\C3> 

<book reviewed=''no'> 

<titlo>Xinl and Java</title> 

<author>Hiro9hl Maruyama</author> 

<co9t>$4d. 00</cost> 
</boo}c> 

<book reviewed-' yes* > 

<title>Java in a NUtshell</title> 
<au thor >Fl anni gan< / author> 

<C09t>$39. O0</C0flt> 

<review> 

<ravi€wedBy>Jo8</revlew9dBy> 
<rating>3 . 5</rating> 
</review> 
<review> 

<reviev8(iBy>Bob</r&viewedBy> 
<j^ating>9. 5</rating> 
</revi€W> 
</book> 
</books> 
</bookSter«> 

The document contains a single element hookStore, which \m sub-elements for name, address, and 
books. The books element contains a collection of book elements. Elements may contain one or 
more ^'attributes " such as the reviewed attribute of book, used to indicate whether the book has been 
reviewed or not. Books that have been reviewed contain one or more review elements. 



This data can be modeled by a set of Java classes, such as: 

claaa Bookstore ( 
String naitie; 
Addxeas address; 
vector book3; 

BookStord (String name) (...) 
void setKame (String name) (...) 

) 

class Book { 

String author; 
String title; 
float cost; 

Book (String title, string author); 
String getTitleO (...) 
string getAuthorO (..] 



class HeviewedBook extends Book ( 
Vector reviews; 

void addReviev (Review review); 

Vector getReviewaO ( return reviews; } 
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The goal of the API is to let the developer construa the data using Java only, then somehow convert 
the classes to XML and later re-construct the contents of the Java classes from the XML file. For 
example: 

Bookstore bookstore - new Bookstore (^^Thc Programmer's Book Store* ) ; 
BooXStore*5etAcldrea3( new Addxeaa ("1 Maple St.*, "Midciletown' , "MJ' ) ); 

Book book = new Book {''Java in a KutaheXl', "Flannigan' ) ; 
Book.setcost (49.0£); 
Bookstore . add ( book ) ; 

3av9TQXttd(bookStorCr ''bookstore. ^onl' ) ; // a hypothetical xnethod 
// later, read the contents back to Java 

Bookstore bookstore ^ Re adFrottOtal (''books tore. xml' ) ; // a hypothetical method 
Collection books « bookStore^getBooksO; 

The next section describes the API and mechanism used to accomplishes this. 

XML to Java API 

The XmlReaderWriterlnterfacQ 

In order to convert user-defined types to XML, such as Bookstore, Book, and Review in the above 
example, each must include some instructions about how to do the conversion. The API needs to 
know: 

• Which fields inside the Java object should be saved to XML? We may want the Java class to 
contain other fields that are used internally and should not get converted. 

• For each field that we want converted, what tag name should be used when generating the 
corresponding XML element. 

• When reading an XML file and constructing the Java objects, what classes should be instantiated 
for each element? We want to be able to support different classes and different Java 
implementations using the same XML representation. 

The Java to XML API accomplishes this by defining the XmlReaderWriter interface. Any class that 
we wish to convert to XML or construct from an XML document must implement this interface. 
The interface is defined as follows: 

interface xsUReadeifWriter ( 

FioldDescriptionO getrieldDeacriptions (} ; 
void aetAttributesCHaahtablc ht) ; 
Hashtable getAttributes { ) ; 

) 

The first method getFieldDescripUons is required. This allows the class to define how it should be 
converted. Typically, this will add just one line of code for all sub^elements contained by the class. 
The second two methods are optional, and are not used if the class does not use attributes as 
mentioned above. The FieldDescription class is described in the next section, but to illustrate it's 
use, the BookStore class fi'om the last example can add the following lines of code to implement it: 
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claas Bookstore { 

public FieldI>e3crdption[] gstFieldDescriptioxis () I 
return new FleldDeacclptlon(] { 

new FieldDe3cxiption< "name'. String, class, ''getNajne', "setNainc^), 
new FieldDe3cription ("address*, Addresfl. class, '*getAddreed' , ^'setAddreae' ) ^ 
new FieldDescription ("books', Vector. clasa, ''getBooks', "setBooks', 
Book. class, *^book'), 

); 

) 

public void setAttributes (Hashtable ht) (;) // not used 

public void Hashtable getAttributeaO { return null/ ) // not used 

} 

Note that the BopkStore class onJy needs to describe fields dirertly contained in it. Sub-elements 
such ti3 Address and Bock (contained in the collection) will provide their own descriptions by 
implementing the interface. 

The FlBkf09Scriptlon Class 

The FieldDescription class provides the set of information needed by the API to convert between 
Java and XML representations. The FieldDescription class has the following constructors: 

FieldDescription (String tagName, Class objectClaas, String getMethod, String setHethod); 

FieldDescription (String tagName, Class objcctclasa, String getMethod, String setMethod, 
Object contentciaflses) / 

FieldDescription (String tagName, Class objectClaas, String getKethod, String setMethod, 
object contentClaases, object ContantTaglfaned) ; 

For simple elemems, the fu^st constructor is used. When a field is represented as a Collection, 
Hashtable or an array, the second forms are used to describe the elements in the collection. 

For the first form, the parameters are: 

• TagName - when writing this field to XML, what name should be used for the corresponding 
XML element tag. 

• OhjectClass - Specifies the Class to instantiate when constructing this field from XML 

• GeiMelhod- The name of the Java method to invoke to retrieve this field. 

• Seihdetkod - The name of the Java method to invoke to retrieve this method. 

The contentClass parameter is used to specify what class of object must be instantiated and 
constructed from the element. It may be any one of the following: 

• A single Class object. In this case, all elements will be represented by the same class. 

• The class may be based on element tag name. In this case, the parameter passed in is a 
Hashtable, where the keys are the element names and the values are the corresponding Class 
types. 

e The class may be based on an attribute value contained in the elements. In this case, the 
parameter is a Hashtable where they keys are specified in the form ''attrName^attrValue " and 
the values are the Class types to use. 
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A containing class must also specify the elemant names to use for each field when writing them to 
the XML document. Hie contentName parameter may be any of the foUowing: 

• The same name for all elements. In this case, pass a single Stiing containing the name to use. 

• The name may be obtained by invoking a ''gef ' method on the object. In this case» you must 
specify a method name preceded by an (e.g. "@getMyN8me")- This method must take no 
parameters and return a String. 

• The name may be based on the class of object. In this case, the keys should be the Class types 
and the corresponding values should be the tag name to use. 

• Based on Hasfatable keys, if collection is an in stance of java.util.Hashtable. In this case, use the 
FieldDescription constructor that does not take a contentName parameter. 



In order to support inheritance, subclasses only need to define FieldDescriptions for new elements, 
and simply concatenate the FieldDescriptions of the parent class. For this purpose^ the 
FieldDescription class has a concat method to make this easy. For example, the ReviewedBook 
class inherits fi'om the Book class, so it's gelFieldDescription method could be written as: 

class ReviewedBook extends Book { 

public FieldDescription n getFieldDescriptlons () { 
FieldDescription [] fda = new FieldDeflcription[J { 

new rieldD©5cription ("reviews', Vector. class, "^getRevlewe' , *'seCRevaews' , 
Review. claaa, '^reviews' ) 

); 

return FieldDescription. concat ( fda, super . getFieldDescriptlons 0 )/ 



For the case of the book collection, we may just constnict a Book object for each element if all we 
are interested in is the base class. However, if we want to construct a different type, depending on 
the attribute, we may do that as well. We can modify the contmClass parameter to be a Hashtable, 
and specify the type based on attribute: 

Hashtable ht ^ new KashtableO; 

ht-put ('•reviewed^yes' , ReviewedBook. class) ; 

ht.putf^'reviewedvno', Book. class) ; 



Now the API can determine what type of class to instantiate based on attribute. 
Attributes vorsus Elements 

It is up to an implementation to decide x^ether to use elements or attributes. For example^ consider 
a User object: 

User ( 

string id; 
String lastKame; 
String firstName; 
String phoneNUinbor 



fd - new FieldDescription(*'booka', Vector. class, **getaooks 
ht, ^Wk'); 



"setBooks*, 
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b this object model, id. lastName.firstName and pkoneNumher are considered "attributes'* of User. 
In XML, this may be modeled as either: 

<U3er> 

<icl>1001</id> 

<last:KaTae>Smith</la3tNajQe> 

<fir3tNazn£>Joe</fir3tNattie> 

<phoneNUinbcr>732-222-1234</phoneNUxnb©r> 
</uaer> 



or as 

<U5er id-' 12345 '> 

<1 as tName>Smi th</l as cNama> 

< f Ir s tNiune> Joe </ f i ra tNamO 

<phoneNuinber>732-222-1234</phoneNUnber> 
</uaer> 

For the second case, rather than describing /rf with a FieldDescription. it wouJd be treated as an 
attribute in the User class: 

Class u^er ( 

string Id - null; 

FieldDeflcriptionf] getFieldDftscriptions (} { 
return new FieldDe3cription(] { 

new FieIdDeflcription('Ua3tName', String, claaa, ^*getLaatN«iie' , "setl^aatNaae* ) , 
new PieldDe»cription(^*firstName', string. class, "g^tfirstName' , aetPiratKaine') , 
new FieldDeacxiption(**phoneNunb^r' , String. claas, "gctNUinber' , **3etNuinber' ) , 

1; 

) 

Hashtable getAttrlbutes () ( 

Hashtable ht ^ new HashtabloC} ; 
ht.put(nd', id); 
return hr; 

) 

void setAttriuteslHaahtablo ht) ( 
String a » ht.get ("id') / 
it{ 9 I* null ) this. id - new String(a); 

) 

) 

ThBXnUmctoss 

This class provides static methods that load and save Documents to and from IQAL streams as well 
as converting Document objects to and from specified Java classes. For the above book store 
example, the complete code needed to save the Bookstore to an XML file and later restore it is as 
follows: 

// construct a book store and populate it with books... 
Bookstore bookstore s new Bookstore (..) ; 
Book book B new &ook(..); 
BookStore. add (book); // etc. 

// turn it into a Document object and dave to an )QfL file 
Document doc - XmlUtll. getDocument ("bookstore* , bookstore); 
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XmlUtil«writeXna(doc, **books.xiuX') ; 

// later, reload the book store from jckl 
Document doc • XnlUtil.readXnaC^books.xml'); 

Bookstore bookstore «= (Books tore )XjTautil.getobject (doc, Bookstore, class) ; 
Collection books = bookstore « getBooka () ; // do something with books 

The readXml and writeXml are used to read and write Documents to and from XML files (or more 
generally streams). The conversion from a Java object to XML is accomplished by: 

Document XadUtiLgetDoctiinent (String docName, Object obj); 

As long as the top level object and contained objeas implement XmlReaderWriter, the whole 
collection can be handled by this call. To convert a Document to any class implementing 
XmlReaderWriter, use: 

Object XalUtil.getObJect (Document doc, Class objectciass) ; 

An instance of obJectClass will be instantiated and queried for it's FieldDescriptions, From that 
point the API can determine how to convert all nodes that it encounters. This works recursively 
through the whole document tree. As mentioned, different object classes can be used to produce 
different results. 

Summary 

The API described here is a simple yet powerful mechanism for converting between Java and XML 
representations. It can be easily applied to any application that is written in Java and is using XML 
as an external data exchange format. The mechanism will work with any XML parser that 
implements the standard W3C Document Object model. XML representations are easily converted 
directly into the Java objects and data types used by developers within their application. 
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